fix(metadata-protocol)!: a package-less row at a holder's exact address answers one thing on every read and in every hydration state: declined for a sealed type, refused with two holders for an overlay type (ADR-0150 D4) - #32741

Requested by Sales · project thread
Fixes #32568

Clause-②: yes (narrowing)
Metadata-protocol: narrowed
Skills-docs: none — skills/** and content/docs/** teach no exact, draft or layered read of a package-less row of a name a package holds; the prescription ships in the refusal text and the FROM → TO below.

维护者速读

• 改了什么：不属于任何包的元数据行（package-less row）在某个持有包的精确地址（?package=X）上，按类型类别只给一种答案：可覆盖类型（email_template、dashboard、report）两个包同名时，草稿读、预览、分层读的 draft 层也一律 409 列出全部持有者；封闭类型（action、queue、hook 等）一律不采用这行，返回持有包自己的条目；读侧回填不再把这行塞进「第一个注册的包」的槽位。
• 为什么改：ADR-0150 D4 与 ADR-0126 Regime C，按专题裁决 6817768147 落实：同一行数据在回填前后、草稿与正式读之间答案不同，属于「歧义被猜而不是被报告」（专题红线 2）。
• 风险与回滚：只改读路径，不改存储与 schema；第一方组合里没有两个包同名又带无包行的情况，计数为 0。回滚即 revert 本 PR。
• 先看：packages/metadata-protocol/src/protocol-registry-hydration.ts（回填不再借第一个包的外壳）、packages/metadata-protocol/src/protocol-meta-item-reads.ts（草稿与预览出口）、packages/metadata-protocol/src/protocol-exact-qualifier.ts（declinedCopyReplaced，平读与分层读的 code 层都先过它）。
• 两分钟验证：pnpm --filter @objectstack/objectql exec vitest run src/package-scoped-exact-qualifier.test.ts，预期全部通过，其中 [#32568] 一组覆盖四种状态 × 两种注册顺序。
• 需要你做的：无，席位落地。

What changes

A package-less row (a sys_metadata row bound to no package, or its copy in the registry's bare slot after a hydration) met at a holder's exact address now answers one thing on every read and in every hydration state, by type class (epic ruling 6817768147 on this card; ADR-0150 D4, ADR-0126 Regime C):

• Overlay types (email_template, dashboard, report): the row is a holder's customization. Two holders: 409 RESOURCE_CONFLICT, ambiguous-in-closure, naming every holder, on the strict draft read, the preview and the layered draft layer as on the active read; the list scoped to a holder no longer previews such a draft. One holder: served, as before.
• Sealed managed types (artifact-backed, no overlay channel): the row is declined on every read at the address (active and its registry or service copy, strict draft, preview, layered read with its code layer, layered draft layer). The address serves the holder's own shipped item, with one holder or two. The bare read of a two-holder name keeps its 409.
• The read-side hydrator (hydrateOverlayIntoRegistry) never borrows an envelope through a package-less lookupArtifactItem: a package-less row wears its one holder's envelope, none with two holders, and a sealed type's declined row is not registered at all. A copy registered before the package arrived is healed by the one heal walk.
• Upgrade guide: semantic entry package-less-row-exact-address-by-type-class (packages/spec/src/migrations/entries/semantic/18.package-less-row-exact-address-by-type-class.ts), registered by the changeset (adr-0087: registered), with its own @objectstack/spec patch changeset. The remedy for a sealed type turns on whether it has a declared override channel (ADR-0146): flow and action (under D9's conditions), page, app, dataset, doc, book and mapping move the change to a declared override in the holder's .custom package; every other sealed type (hook, job, queue, sharing_rule, assignment_rule, agent, skill, api, …) has none, so the row is deleted and the change ships in a new version of the holding package, or lives under a name no package ships.

Branch note (Duplicate Fix Guard): this branch, claude/project-thread-pjmygu, continues claude/project-thread-cyidlz@191cd2fab (the previous holder's pushed WIP for this card) with origin/main merged in, never rebased; claude/project-thread-cyidlz is left as it was.

Merges with main after the ACCEPT on a5a3a66a9 (no rebase):

• 7b43a0f74 merges 7e7277c98 (fix(metadata, metadata-protocol, core)!: the bare read and removal of an action name judge the loaders' slots beside the registry's, tell the platform's package-less item from the environment's, and remove what the bare read answers (ADR-0150 D3) #32719, feat(types, rest, metadata-protocol)!: a package-scoped refusal names its candidates on every /data write door #32740). Three hunks in two files, each a union: readMetaItem's and getMetaItemLayered's host Pick carry main's getServicesRegistry beside this branch's isStoredEntryOfDeclinedName; the layered read imports main's judgeDroppedServiceRefusal and servedFromDisabledHolder beside this branch's packageScopedRefusalOf. Main's changes judge the bare read (no package), this branch's the exact address; main still pins the lead route on the environment's item, so row 11's FROM stands.
• 5659f216d merges 2f80f2897 (fix(objectql, metadata-protocol)!: by-name doors judge a name's holders over the served set, so a disabled package's item is not a holder (ADR-0150 D3) #32497, the served holder set). One textual hunk: both sides appended a describe to package-scoped-exact-qualifier.test.ts; both are kept. Beside it, a second kind of hand edit, in the same file: three of fix(objectql, metadata-protocol)!: by-name doors judge a name's holders over the served set, so a disabled package's item is not a holder (ADR-0150 D3) #32497's pins asserted the D4 customization answer for a sealed type with the other holder disabled (agent; action plain and layered); by ruling 6817768147 they now pin the holder's own item with fix(objectql, metadata-protocol)!: by-name doors judge a name's holders over the served set, so a disabled package's item is not a holder (ADR-0150 D3) #32497's answer named in the title (row 13). dashboard keeps fix(objectql, metadata-protocol)!: by-name doors judge a name's holders over the served set, so a disabled package's item is not a holder (ADR-0150 D3) #32497's answer. 533a4f932 adds pins for one holder disabled while the read-side hydrator runs, then re-enabled (email_template, action, queue): one answer per state, nothing left behind by the hydration.

FROM → TO

Unchanged, pinned as CONTROLs: the bare read of a two-holder action (409, after the hydrator too); an overlay type's package-less row with one holder (served on every exit, and the hydrator lays it in under that holder's envelope); email_template with two holders (409 naming both, before and after the hydrator, and the first holder's slot keeps its own).

The widening in rows 5, 5b, 6 and 12 (action, and agent, skill, app, with two holders: 409 → 200 the holder's own item) rests on the epic ruling on this card, 6817768147: with the row declined, ?package=X serves X's own shipped item, exactly as it would with no row stored. The same declining moves an answer on the dataset query door (POST /analytics/dataset/query and its batch door), which reads each holder at its exact address (#32804): with a package-less dataset row beside two holders, each holder's exact read no longer refuses, so #32804's "every holder's own read refuses → 503 for every caller" no longer fires for that composition. The bare, ?callerPackage= and non-holder ?package= arms move from 503 to the admission-judged answer (404 admitted to neither; 200 running the one admitted holder; 409 naming only the admitted holders), and ?package=<holder> moves from 503 to that holder's own dataset (widening). The package-less row never runs. Measured on 023ace703 with #32804's rig: alpha admitted only → bare and ?callerPackage= 200 alpha_item, ?package=<non-holder> 409 naming alpha alone; neither admitted → 404; both → 409. No @objectstack/rest product code changes, so no rest changeset.

No export is added: declinesPackageLessRowAt, isPackageLessRow and declinedCopyReplaced are module-internal (not in src/index.ts).

Tests

• packages/objectql/src/package-scoped-exact-qualifier.test.ts: a new [#32568] describe. Locations 1 and 3 (draft exits, overlay two holders refused, one-holder CONTROL, sealed declined with one holder and two); location 2 (the five types); location 4 for action and queue in four states (not hydrated, after the read-side hydrator, bare-slot copy stamped '', stamped sys_metadata) × both registration orders, the one-holder flip, the bare-read CONTROL, and the overlay CONTROL. The [#31699] and [#32407] pins whose answers this moves are rewritten in place with the old answer named in the title.
• protocol-boot-hydration-scoped.test.ts, protocol-registry-shadow.test.ts: the legacy first-match graft pins now pin that a sealed type's package-less row is not registered over the package's item.
• packages/objectql/src/package-scoped-exact-qualifier.test.ts (contract review S1): a metadata service answering a package-less copy, for action and queue with one holder and two: the plain read and the layered read's code layer both answer the holder's own. All four failed before the layered fix (the code layer answered stored, or 409 for action with two holders) and pass after it.
• packages/runtime/src/action-package-addressing.test.ts: the describe's docblock now states the route reads each holder's exact address, where the package-less copy is declined (runtime action route: an environment action on an object neither of two holders binds cannot run through the bare route once #32568 lands #32751 for the execution face).
• protocol.lookup-artifact-item-call-sites.test.ts: the census rows for the hydrator's lookup and the new declinedCopyReplaced lookup.
• packages/rest/src/analytics-routes.test.ts (merge queue, after fix(rest): the dataset query door judges admission on the refusal arm before it names holders (ADR-0150 D3 after ADR-0149 D2) #32804): fix(rest): the dataset query door judges admission on the refusal arm before it names holders (ADR-0150 D3 after ADR-0149 D2) #32804's two 503 cases (a holder whose own exact-qualifier read refuses…, ?package= naming a holder whose own address refuses…) made each holder's exact read refuse by registering a package-less dataset row beside both holders. dataset is a sealed type, so that row is now declined at each holder's address and the read serves the holder's own (the queue run read 404 and 200 where 503 was pinned). The cases now throw that read's former refusal (ambiguous-in-closure naming both holders) from the holder's exact read, so the 503 they pin is unchanged; a new [#32568] pin holds the declined row: ?package= runs the holder's own dataset. Ablation: without the rig both cases fail, 2 failed / 55 passed.

Acceptance notes

• Sweep of other exact-read exits: the active read, strict draft read, preview, layered read and its draft layer, and the scoped list's preview are judged here. The history, audit and diff doors (/meta/:type/:name/history and siblings) read the event ledger by (type, name) and serve no item at an exact address; they are not swept by this PR.
• Line budget: 14 files, +725 −89, under the ruling's ~1500, so location 4 ships here, not in a second PR.
• Not in this PR, filed under metadata-protocol: a package-less item of a two-holder name is still served at both exact addresses on the draft and preview reads and for hook, job, queue, sharing_rule and assignment_rule (ADR-0150 D4, after #32407) #32568 and on hold: the bare read of a one-holder name before a heal walk still answers a copy registered before the package arrived (row 7's bare half is pinned for the hydrated states only), metadata-protocol: the bare read of a one-holder sealed name still answers a package-less copy registered before its package arrived, until the next heal #32752.
• Not in this PR (contract review S4 on 533a4f932; epic red-line read 6835864200: this PR need not heal it, metadata-protocol: re-enabling a package leaves another holder's registry slot answering a package-less overlay row hydrated while it was disabled #32820 (p1, under metadata-protocol: a package-less item of a two-holder name is still served at both exact addresses on the draft and preview reads and for hook, job, queue, sharing_rule and assignment_rule (ADR-0150 D4, after #32407) #32568) carries the re-enable heal): with one of two holders disabled, the read-side hydrator lays an overlay type's package-less row into the enabled holder's registry slot under its envelope, and re-enabling the other holder does not re-hydrate, so registry-direct readers of that slot (getPackageScopedItem), the list scoped to it and its execution list answer the environment's row as the holder's own until the next unscoped hydration. Measured on 533a4f932: email_template A's slot holds env en-US stamped com.acme.alpha after B is re-enabled; action and queue slots hold each holder's own (metadata-protocol: the bare read of a one-holder sealed name still answers a package-less copy registered before its package arrived, until the next heal #32752 comment 6835724023). The protocol's exact reads are unaffected (409 naming both, pinned); the pin's title and comment now claim the exact read only and name this case.
• Row 11 moves a pin of seat ruling B (packages/runtime/src/action-package-addressing.test.ts, case 2): the route's answer on lead rode the defect this card closes. Measured on origin/main's metadata-protocol source under this branch's test: ?package=alpha answered the environment's item (env, on lead) and ?package=beta its own (beta, on contact). The execution face reading the environment's own item (_env) is runtime action route: an environment action on an object neither of two holders binds cannot run through the bare route once #32568 lands #32751, as ruling B records.
• First-party count: 0 (no composition here has two packages holding one name with a package-less row; the full dogfood battery is run on the final head and reported on the card).

Verification

Merge-queue round on head 023ace703 (merges main 5c0f11349 at 176315702, no textual conflict; 023ace703 changes packages/rest/src/analytics-routes.test.ts only):

• Queue run 43312543280 failed on Test Core (5/8): the two #32292 cases above, a semantic conflict with fix(rest): the dataset query door judges admission on the refusal arm before it names holders (ADR-0150 D3 after ADR-0149 D2) #32804, not a flake.
• pnpm --filter @objectstack/rest test on 023ace703: 407 files passed; 8131 tests passed, 332 skipped. tsc --noEmit for rest exit 0; eslint on the test file exit 0.
• Product source is unchanged since 103d267b7; the readings below stand for it, and CI on 023ace703 covers the rest.

Measured on head 533a4f932 (merges main 2f80f2897), after the dogfood closure build (turbo run build --filter='@objectstack/dogfood^...', VERDICT 0):

• pnpm --filter @objectstack/metadata-protocol test: 337 files passed, 7 skipped; 22786 tests passed, 36 skipped. Typecheck exit 0 for metadata-protocol, objectql and runtime.
• pnpm --filter @objectstack/objectql test: 589 files passed; 12626 tests passed (the three rewritten fix(objectql, metadata-protocol)!: by-name doors judge a name's holders over the served set, so a disabled package's item is not a holder (ADR-0150 D3) #32497 pins and the six disabled-holder hydration pins included).
• pnpm --filter @objectstack/runtime exec vitest run src/action-package-addressing.test.ts: 67/67 (main's metadata: in-process bare action reads disagree with the protocol on package-less holders, and a bare removal beside one package takes every slot (ADR-0150 D3/D4, follow-up of #32365) #32560 cases beside this card's row 11 pin).
• pnpm lint: exit 0. node scripts/pm/dispatch-gates.mjs --commands: 92 derived, each exit 0 after pnpm --filter @objectstack/spec build; --ran: 92 derived, 92 run, 0 NOT-MEASURED, 0 UNRUN.
• S1, measured before its fix: the four service-copy pins failed against the layered read without declinedCopyReplaced and pass with it. Hydrator ablation (on 55a9c1f24; the hydrator is unchanged since): 9 failed / 202 passed with both hunks put back, 211/211 restored.
• Dogfood under the verify lock: 455 files passed, 3 skipped; 3817 tests passed, 42 skipped; VERDICT command-exit 0.
• CI on 533a4f932: 56 check runs success, 11 skipped, none failed; mergeable clean.
• 103d267b7 on top changes text only: the changeset (row 13 and the disabled-holder narrowing on the Clause-② line) and the hydration pin's title and comment (git diff --stat 533a4f932 103d267b7: 2 files changed, 10 insertions(+), 5 deletions(-)). package-scoped-exact-qualifier.test.ts 217/217 and both changeset gates exit 0 on it.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic (one migration entry).
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint is run on the final head.
• 4. One issue, one branch, one pull request (the branch continues the previous holder's, merged with main).
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: one entry file; the registry, spec-changes.json and the upgrade guide are generated, git-ignored projections.
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01L6bhgV84zNSi6HwSHmMU2c